<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Packages - Fuel Documentation</title>
	<link href="../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/nav.js"></script>
	<script type="text/javascript" src="../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('general', '../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">

		<h2>Packages</h2>

		<p>
			When it comes to organizing, reuse and share your code, packages are a great way to allow you to do this.
			They can contain all sorts of code like models, third-party libraries, configs and so on.
			Packages also allow you to extend the core without messing up you app/classes directory.
			To clearify what packages are, here are the "is" and "is not" on packages.
		</p>

		<h4 id="they_are">Packages...</h4>
		<ul>
			<li>are a great way to organize your code,</li>
			<li>supply a place to keep third party libraries,</li>
			<li>allow you to extend other packages without messing with someone's code,</li>
			<li>a place to extend fuel without messing with core files.</li>
		</ul>

		<h4 id="they_are_not">But..</h4>
		<ul>
			<li>packages do not map to the URL,</li>
			<li>and are not approachable through HMVC requests</li>
		</ul>

		<h3 id="installing">Installing packages</h3>
		<p>Installing packages can be done manually and through <a href="../packages/oil/package.html">oil</a>. To install manually download the packa source and place in into your package directory (default in fuel/packages).</p>
		<p class="note">To actualy be able to use your it you must either always_load it in <em>app/config/config.php</em> or use <a href="../classes/fuel.html#method_add_package">Fuel::add_package()</a>.</p>

		<h3 id="creation">Creating packages</h3>
		<p>To help people understand what you are doing it's best to stucture your package like so:</p>

		<pre>/packages
    /package
        /bootstrap.php
        /classes
            /your.php
            /classes.php
            /here.php
        /config
            /packageconfig.php
        /and_so_on
</pre>

		<p>
			Every package is expected to have a <em>bootstrap.php</em> located at the base of the package.
			Use the bootstrap to add the package namespace (to global if you wish). And add the classes for better perfomance.
		</p>

		<pre class="php"><code>// Add namespace, necessary if you want the autoloader to be able to find classes
Autoloader::add_namespace('Mypackage', __DIR__.'/classes/');

// Add as core namespace
Autoloader::add_core_namespace('Mypackage');

// Add as core namespace (classes are aliased to global, thus useable without namespace prefix)
// Set the second arguement to <kbd>true</kbd> to prefix and be able to overwrite core classes
Autoloader::add_core_namespace('Mypackage', true);

// And add the classes, this is usefull for:
// - optimization: no path searching is necessary
// - it's required to be able to use as a core namespace
// - if you want to break the autoloader's path search rules
Autoloader::add_classes(array(
	'Mypackage\\Classname' => __DIR__.'/classes/classname.php',
	'Mypackage\\Anotherclass' => __DIR__.'/classes/anotherclass.php',
));
</code></pre>

		<p>Once you have your classes in place you can now start using them.</p>

		<p class="note">Note: if package namespaces aren't aliased to global you must supply the it:</p>

		<pre class="php"><code>// If aliased to global just use
$instance = new Myclass;

// When not aliased to global
$instance = new Mynamespace\Myclass;
</code></pre>

		<h3 id="fuelcells">The future of packages, fuel cells...</h3>
		<p>Comming soon...</p>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
